Index Files

An index file is the default file that NGINX serves when a client requests a directory URI (i.e., a URL ending with /) without specifying a filename.

For example:

http://example.com/   → NGINX serves /var/www/html/index.html

This avoids 404 errors and allows automatic loading of homepage or default page.

Core Directive: index

index file1 file2 ...;

Context: http, server, location

Explanation

• NGINX tries each file in order until one exists
• Stops at the first match
• Can be overridden per location

Simple Example

server {
    listen 80;
    server_name example.com;

    root /var/www/html;
    index index.html index.htm;
}

Behavior

Request	Resolved File
/	/var/www/html/index.html
/about/	/var/www/html/about/index.html
/docs/ (no index)	404

index Directive in Location Blocks

You can override default index behavior per path:

location /docs/ {
    index home.html main.html;
}

Request: /docs/ → NGINX checks:

1. /var/www/html/docs/home.html
2. /var/www/html/docs/main.html

First existing file served

Interaction with try_files

For modern setups, try_files is often combined with index:

location / {
    try_files $uri $uri/ /index.html;
}

• $uri → file requested
• $uri/ → directory requested → check for index
• /index.html → fallback for single-page apps (SPA)

Common for React, Angular, Vue apps

Directory Index Listing

NGINX does not automatically list files if no index exists (returns 403/404)

To enable listing:

location /downloads/ {
autoindex on;
index index.html;
}

If index.html exists → served

Else → directory listing

Examples With Multiple Index Files

server {
   root /var/www/html;
   index index.php index.html index.htm;
}

NGINX checks in order:

1. index.php → for PHP apps
2. index.html → fallback
3. index.htm → last resort

Useful for sites with legacy files

Index Files and Reverse Proxy

When NGINX is used as a reverse proxy, you can still serve static index files:

location / {
root /var/www/app;
index index.html;
try_files $uri $uri/ @backend;
}

location @backend {
proxy_pass http://backend;
}

• Static files served directly if they exist
• Requests for missing files forwarded to backend

Index Files in HTTPS

server {
    listen 443 ssl;
    server_name example.com;

        root /var/www/html;
        index index.html;

        ssl_certificate /etc/ssl/certs/example.crt;
        ssl_certificate_key /etc/ssl/private/example.key;

    }

Behavior

• same as HTTP
• Index files are critical for default pages under SSL

Common Mistakes

Mistake	Effect
Not defining index	403/404 on directory access
Wrong order of files	Wrong file served
Missing trailing slash in directory	301 redirect occurs
Index file missing	404
Conflicting index in locations	Unintended file served

Debugging Index Issues

Test with curl:

curl -I http://example.com/

• Check Location: header (redirects)

Check NGINX error logs for missing index files:

tail -f /var/log/nginx/error.log

Best Practices

• Always define index in http or server context
• Use multiple files in order for backward compatibility
• Combine try_files for SPA applications
• Avoid exposing directory listings unless intentional
• Ensure proper file permissions for security

Real-World Production Example

    server {
    listen 80;
    server_name example.com www.example.com;

        root /var/www/example;
        index index.php index.html index.htm;

        location / {
            try_files $uri $uri/ /index.php?$query_string;
        }

        location ~ \.php$ {
            fastcgi_pass unix:/run/php/php-fpm.sock;
            include fastcgi_params;
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        }

    }

• NGINX serves static index files if they exist
• Falls back to PHP for dynamic pages
• Ensures backward compatibility and SPA support

Summary

• index files define default page for a directory request
• Directive supports multiple files in order
• Works with root, alias, try_files, and proxy setups
• Critical for serving static sites, SPAs, and default landing pages
• Must be combined with proper security and caching for production